Node / deuxyeux / RTNode-HeltecV4 rns://bfb3becae4b7568796ac5276b6bc5741/deuxyeux/RTNode-HeltecV4

Mirrored from rns://8d583d150cea7bdc2360dd1759690ee3/public/RTNode-HeltecV4 synced 54m ago

A custom firmware for the Heltec WiFi LoRa 32 V4

󰉖 Files • 󱌣 Work (0) • 󰋚 Commits (53) • 󰘬 Branches (1) • 󰓼 Tags (0) • 󰋑 Thanks (1) •  Stats

• Bidirectional LoRa ↔ TCP bridging — local LoRa mesh nodes can reach the global Reticulum backbone and vice versa

• Web-based configuration portal — WiFi SSID/password, backbone host/port, LoRa parameters, all configurable via captive portal

• OLED status display — real-time status indicators for LoRa, WiFi, WAN (backbone), LAN (local TCP), plus IP address, port, and airtime

• Optional local TCP server — serve local devices on your WiFi in addition to the backbone connection

• Automatic reconnection — WiFi and TCP connections recover from drops with exponential backoff

• ESP32 memory-optimized — table sizes, timeouts, and caching tuned for the constrained MCU environment

• Dual board support — supports both Heltec V3 (8MB flash) and V4 (16MB flash, 2MB PSRAM) with automatic board and PSRAM detection

This firmware was designed for the Heltec WiFi LoRa 32 V4. This board was chosen for its 2MB PSRAM and LoRa capabilities. While the V3 is supported, it uses the ESP32-S3FN8 which has no PSRAM. The firmware detects PSRAM at runtime and allocates the TLSF memory pool from SPIRAM when available, falling back to internal SRAM (~170 KB) on boards without PSRAM.

The easiest way to flash a pre-built firmware. You only need Python 3 and a USB cable.

T282828

git clone https://github.com/jrl290/RTNode-HeltecV4.git

Tffa657cd RTNode-HeltecV4

T8b949e# Download latest firmware from GitHub Releases and flash

T8b949e# (auto-detects V3 vs V4 from flash size)

python flash.py

T8b949e# Optional: use your machine's installed esptool instead of the bundled copy

python flash.py --use-system-esptool

T8b949e# Or specify board explicitly

python flash.py --board v3

python flash.py --board v4

T8b949e# Or flash a local binary

python flash.py --file rtnode_heltec_v4.bin

By default, T383838flash.py uses the bundled T383838Release/esptool/esptool.py for reproducible flashing. Only use T383838--use-system-esptool if you explicitly want to override that with a host-installed esptool.

The flash utility auto-detects whether a V3 or V4 is connected by querying the flash size (8MB = V3, 16MB = V4). You can override with T383838--board v3 or T383838--board v4. It will list all available serial ports and prompt you to choose one. If no ports are detected, you may need to hold the BOOT button while pressing RESET to enter download mode.

For development or customization:

T282828

git clone https://github.com/jrl290/RTNode-HeltecV4.git

Tffa657cd RTNode-HeltecV4

T8b949e# Build for V4

pio run -e heltec_V4_boundary

T8b949e# Build for V3

pio run -e heltec_V3_boundary

T8b949e# Flash (via PlatformIO)

pio run -e heltec_V4_boundary -t upload

T8b949e# Or create a merged binary and flash with the utility

python flash.py --merge-only T8b949e# creates merged firmware bin

python flash.py T8b949e# flash it (auto-detects board)

T8b949e# Monitor serial output (optional)

pio device monitor -e heltec_V4_boundary

If you have the merged binary (T383838rtnode_heltec_v4.bin), you can flash it with a single esptool command:

T282828

esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud T79c0ff921600 Tffea00\

write_flash -z --flash_mode qio --flash_freq 80m --flash_size 16MB Tffea00\

0x0 rtnode_heltec_v4.bin

Replace T383838/dev/ttyACM0 with your serial port (T383838/dev/cu.usbmodem* on macOS, T383838COM3 on Windows).

On first boot (or if no configuration is found), the device automatically enters the Configuration Portal.

The config portal activates automatically on:

• First boot — when no saved configuration exists

• Button hold >5 seconds — hold the PRG button for 5+ seconds, the device reboots into config mode

When active, the device creates a WiFi access point named T383838RNode-Boundary-Setup (open network). A captive portal should appear automatically when you connect; if not, browse to T383838http://192.168.4.1.

The web form has four sections:

After saving, the device reboots with the new configuration applied.

The 128×64 OLED is split into two panels:

T282828

• Filled circle (●) = active/connected

• Unfilled circle (○) = inactive/disconnected

• Labels are UPPERCASE when active, lowercase when inactive (except LAN which is always uppercase)

• LAN row is hidden when the Local TCP Server is disabled in configuration — the remaining layout stays in place

T282828

• Port shows the Local TCP server port (the port local nodes connect to), not the backbone port

• Port line is hidden when the Local TCP Server is disabled

The firmware runs up to three RNS interfaces simultaneously, using different interface modes to control announce propagation and routing behavior:

The LoRa radio operates in Access Point mode. In Reticulum, this means:

• The interface broadcasts its own announces but blocks rebroadcast of remote announces from crossing to LoRa

• This prevents backbone announces (hundreds of remote destinations) from flooding the limited-bandwidth LoRa channel

• Local nodes discover the transport node directly; the transport node answers path requests for remote destinations from its cache

The TCP backbone connection uses T383838MODE_BOUNDARY (T3838380x20), a custom transport mode adapted for the memory-constrained ESP32 environment. In this mode:

• Incoming announces from the backbone are received and cached, but not stored in the path table by default — only stored when specifically requested via a path request from a local LoRa node

• This prevents the path table (limited to 48 entries on ESP32) from being overwhelmed by thousands of backbone destinations

• When the path table needs to be culled, backbone-learned paths are evicted first, preserving locally-needed LoRa paths

If enabled, a TCP server on the WiFi network allows local Reticulum nodes to connect. It also uses Access Point mode, with the same announce filtering as LoRa.

• Each TCP interface must have a unique name to produce a unique interface hash — the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface". Without distinct names, both interfaces produce the same hash, causing the interface map lookup to fail when routing packets.

• TCP interfaces are configured with a 10 Mbps bitrate, which causes Reticulum's Transport to prefer TCP paths over LoRa paths (typically ~1–10 kbps) when both are available for the same destination.

• When the Local TCP Server is disabled, its status indicator (LAN) and port number are hidden from the OLED display.

The ESP32-S3 has limited RAM compared to a desktop Reticulum node. Several customizations were made to the microReticulum library to operate reliably within these constraints:

The most critical optimization: backbone announces are not stored in the path table by default. A backbone like T383838rmap.world may advertise hundreds of destinations. Storing them all would evict every local LoRa path.

Instead:

1. Backbone announces are received and their packets cached to flash storage

2. When a local LoRa node requests a path, the transport node checks its cache and responds directly

3. Only specifically requested paths get a path table entry

4. Path table culling prioritizes evicting backbone entries over local ones

When a transport-addressed packet arrives from LoRa but the transport node has no path table entry for it, the firmware:

1. Strips the transport headers (converts T383838HEADER_2 → T383838HEADER_1/BROADCAST)

2. Forwards the raw packet to the backbone interface

3. Creates reverse-table entries so proofs can route back to the sender

This acts as a default route — any packet the transport node can't route locally gets forwarded to the backbone.

The original microReticulum T383838get_cached_packet() function called T383838update_hash() after deserializing cached packets from flash. However, T383838update_hash() only computes the packet hash — it does not parse the raw bytes into fields like T383838destination_hash, T383838data, T383838flags, etc.

This was changed to call T383838unpack() instead, which parses all packet fields AND computes the hash. Without this fix, path responses contained empty destination hashes and were silently dropped by LoRa nodes.

│ Note: T383838unpack() only parses the plaintext routing envelope (destination hash, flags, hops,

│ transport headers). It does not decrypt the end-to-end encrypted payload. Every Reticulum

│ transport node performs equivalent header parsing during normal routing — this is standard

│ behavior, not a security concern.

The C++ T383838std::map::insert() method silently does nothing when a key already exists — unlike Python's T383838dict[key] = value which replaces. The original microReticulum code used T383838insert() to update path table entries, meaning stale LoRa paths were never replaced by newer TCP paths (or vice versa).

This was fixed by calling T383838erase() before T383838insert(), ensuring updated path entries always replace stale ones. Without this fix, the transport node would continue routing packets via an old interface even after a better path was learned.

Each RNS interface must have a unique name because the name is hashed to produce the interface identifier used in path table lookups. If two interfaces share the same name, they produce the same hash, and T383838std::map can only store one — causing the Transport layer to fail to resolve the correct outbound interface for packets.

The TcpInterface constructor accepts an explicit T383838name parameter: the backbone uses T383838"TcpInterface" and the local server uses T383838"LocalTcpInterface".

In the configuration portal:

1. Set WiFi SSID and password

2. Set TCP Backbone Mode to Client

3. Set Backbone Host to T383838rmap.world

4. Set Backbone Port to T3838384242

5. Save and reboot

On your server, configure T383838rnsd with a TCP Server Interface in T383838~/.reticulum/config:

T282828

Tff7b72[[TCP Server Interface]]

Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface

Te6edf3listen_host Tff7b72= Ta5d6ff0.0.0.0

Te6edf3listen_port Tff7b72= Ta5d6ff4242

Then configure the transport node as a Client pointing to your server's IP.

On your server, configure T383838rnsd with a TCP Client Interface:

T282828

Tff7b72[[TCP Client to Transport Node]]

Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface

Te6edf3target_host Tff7b72= Ta5d6ff<transport-node-ip>

Te6edf3target_port Tff7b72= Ta5d6ff4242

Set the transport node's Local TCP Server to Enabled (port 4242).

The firmware depends on microReticulum T3838380.2.4, automatically fetched by PlatformIO on first build. After the first build, the library sources under T383838.pio/libdeps/heltec_V4_boundary/microReticulum/src/ need the patches described in "Routing & Memory Customizations" above. Key files modified:

This project is licensed under the GNU General Public License v3.0 — see LICENSE for details.

Based on:

• RNode Firmware by Mark Qvist (GPL-3.0)

• microReticulum by Chris Attermann (GPL-3.0)

• Reticulum by Mark Qvist (MIT)